TeX 1995 July/TeX CD-ROM July 1995 (Disc 1)(Walnut Creek)(1995).ISO/dviware/dvidoc/zed-example.out

Text File | 1994-04-24 | 11KB | 289 lines

                              ZED (Zohar EDitor)

                               A. Bruce Langdon
                              Physics Department
                    Lawrence Livermore National Laboratory


          ZED is an interactive code, able to read, manipulate and dis-
     play graphically the time-dependent data from simulation codes.
     ZED was begun in 1974 by B. Langdon and B. Lasinski to postpro-
     cess time history files from runs of ZOHAR, a 2D electromagnetic
     particle-in-cell code.  At Berkeley, Princeton and Livermore MFE it
     was applied and extended in imaginative ways to other codes by W.
     Nevins, N. Otani,..., and others.  In its original (1974-1987) form,
     the commands were individually interpreted in LRLTRAN, adding new
     commands was clumsy, and the command syntax was stilted.  The ver-
     sions at LCC (the internal Livermore center) and at NMFECC evolved
     separately for years.  In 1987 Nevins suggested that ZED be re-
     born as a Basis `package'.  Basis is a combined interactive inter-
     preter/graphics/code system to which anyone can readily add commands
     and the Fortran subprograms to implement them.  This document de-
     scribes the Basis implementation of ZED.


                                 Availability

     At MFECC, ZED for the Cray-2 is publicly available from CFS directory
/ZOHAR/CRAY2/ZED.  The files include:
     XZED is the executable file.
     ZEDLIB is a LIB file which includes ZEDMAC, the part of ZED written in
the Basis language, and the sources files needed to make XZED. Also, ZED.TEX
is the TeX source for this manual; ZED.DOC (what you are reading now) is a
straight ASCII file to print or view on a terminal.  EBAL is a Basis-language
file; read after INIT, it will read and display the various particle and field
energies and fluxes and form an energy balance.  PBAL is like EBAL, but for
the x-component of momentum.


                              How to use ZED now

     First, get a copy of the Basis system manual[1] and read the first chap-
ter.
     Commands implemented now let you create Basis variables that contain the
time histories of physical variables from their time histories saved in the
HISTORY and STATE files.  You then have the full power of Basis to do as you
will with them.  This already empowers you to do much of what old ZED did, and
much more that it didn't.
     The time dependence of many quantities in the simulation is written into
the file HISTORY. The file STATE contains in addition the time step, particle
species' names, etc, and descriptive information about the simulation (plus
other data like the electromagnetic fields that pertains only to the time step
when the state file was made.)  HISTORY and STATE are not human readable text



11/21/1988
ZED

files, they hold numbers and text in Cray hardware representation.(a)  The
Fortran functions GETSTATE and GETHIST, together with the Basis-language func-
tions INIT, READH, etc., read from STATE and HISTORY and create Basis vari-
ables holding the interesting values.

INIT      The first command you give is INIT. Often the files are renamed to
          indicate the problem name (e.g., HPROB, SPROB) or time step (e.g.,
          H6000, S6000).  Then you run `INIT PROB' or `INIT 6000'.

GET       A list of variables to be read from HISTORY is accumulated.  Vari-
          able `ELG' is added to the list by the command `GET ELG'. This
          translates to `GETS("ELG")'.  You may call `GETS' directly if the
          variable name is computed.  For example, `GETS("KE"//FORMAT(IS,0))'
          when IS=2 adds `KE2' to the list.

READH     This command takes the list accumulated by the `GET' commands, reads
          from HISTORY, and creates Basis arrays holding the time series.  In
          the example above, after readh there will be two new arrays, ELG and
          KE2.  You then could do `PLOT ELG, TIME' to plot the electrostatic
          field energy versus time.

STEPS FIRST, LAST [, ISKIP]  Usually READH reads from step 0 to the last
          step of the simulation.  This command confines the times steps to
          (FIRST,LAST). Optionally it resets ISKIP, whose meaning is that only
          time steps that are multiples of ISKIP are retained.  If ISKIP=2,
          then e.g., ELG(I) corresponds to time step 2I and ELG is subscripted
          roughly (FIRST/2:LAST/2).
          If indexed variables are to be used, ISKIP must be a multiple of
          ISMODE (see MODES).

MODES     HISTORY is divided into two parts.  The first holds time records for
          quantities that are more or less global, like kinetic energy for all
          electrons, or are particular, like the x position of a planar shock.
          The records present are printed by INIT. The second part holds time
          records of quantities that have a name and one or two indices, like
          a field at a particular grid point, or a coordinate of a particle.
          The list in human-readable form is in array LBLM.
          At present, GET and READH work with only one part at a time.  You
          toggle between them with the MODES command.
          Values in the modes section are not in general saved every time
          step, but at steps that are multiple of ISMODE, an input variable
          to ZOHAR. In ZOHAR by default ISMODE=2.

PLOTH XYZ  plots history variable XYZ versus time.  If XYZ is a complex vari-
          able, the real and imaginary parts are plotted using solid and
          dashed lines in the lower half of the frame.  In the upper half, the
          modulus squared is plotted, semilog.  (Of course you can also use
          the Basis plot interface.)
----------------------------
 (a) The format  of HISTORY and STATE is  indicated in source  files SZEDC and
VAR.ZED in  ZEDLIB, and of  course in  the ZOHAR routines  WRITSTAT, READSTAT,
TSET and MDSET.



11/21/1988                             2
ZED

          If XYZ is from the history file, i.e., it is in the VARSH or VARSM
          list, it is labelled instead with the corresponding ``nice'' name
          from LBLH or LBLM (see `Variable naming').

SPECT(F)  Value is the Blackman-Tukey power spectra of time variable F. To
          get spectrum for subinterval of the full time step range (IS-
          TEPL,ISTEPU), do SPECT(F(IL:IU)). Remember, IL and IU are the actual
          steps divided by ISKIP.

SPARAM LAGWIDTH [DATAWIDTH [WMAX]]  Set lag window and data window widths (in
          steps) and maximum frequency to be displayed by default in spectrum
          plots.

INTS VAR [WMIN WMAX]  (Soon) Integrate spectrum in VAR. Useful in finding out
          how much power is between two frequencies.

MEM       (Later) Form `maximum entropy method' spectra.

RESET     Clears memory.  Might be used before switching to another ZOHAR run.

FLL       Prints ZED's memory size.


                               Variable naming


     ZOHAR history records include items whose names have blanks or charac-
ters not legal in Basis variables:  `FIELD PX', `EX-EY'. So you must refer to
`FIELDPX' and `EXEY' instead.  Worse, indexed records have a name and two in-
dices, and an index may be negative.  For example, `BZ(X,KY) 20 3' is field
Bz, Fourier transformed over y, evaluated at x grid point 20, mode 3.  This
is stored in Basis variable `BZXK20$3'.  The $ separates the two indices.  In
a negative index number, a % replaces the minus.  Arrays VARSH and VARSM hold
the list of these ugly things for globals and modes, respectively, while LBLH
and LBLM hold the list of nice names.  You may wish to use Basis' DEFINE so
you can refer to these by nicer names.


                         ZOHAR's variables in HISTORY


     While the modes variables are entirely specified by user input and there
may not even be any, the global variables are chosen by statements at the be-
ginning of subroutine TSET. These vary slightly from version to version and
the number of particle species, but the following are standard:

N1, N2, ...   are the number of active particles of species 1, 2, ...

KE1, PX1, KE2, ...   are the kinetic energies and momenta of active particles
     of species 1, 2, ...





11/21/1988                             3
ZED

KL1, KL2, ...   are cumulative kinetic energies of particles of species 1,
     2, ...  lost due to particles leaving through the left or right side.
     Particles entering make a negative contribution.

L PXL1, R PXL1, ...   are cumulative x momenta of particles of species 1 lost
     due to particles leaving through the left or right side, respectively.
     Particles entering make a negative contribution.

     ..and similarly for PY1, etc.

FIELD PX  Electromagnetic momenta in x direction, etc.

L PXLF, R PXLF  cumulative fluxes of the x component of the field momentum
     out of the system, i.e.  the time integral of the Maxwell stress tensor
     averaged averaged over y at the left and right sides.

ELG, EX-EY, BZ  field energies associated with the `electrostatic' field, Ex
     plus Ey, and Bz, respectively.

WLEYBZ, WREYBZ  cumulative Poynting fluxes.  The electromagnetic energies into
     the left side and out through the right side, averaged over y.

     ..and similarly for BX-BY, EZ, WLEZBY and WREZBY.

BZ LEFT, BZ RIGHT  is Bz averaged over y at the left and right sides.  The
     contribution of the incoming electromagnetic waves is subtracted; this
     only really works in vacuum.

     ..and similarly for EZ LEFT and EZ RIGHT.

CLOCK  is the real clock time in decimal hours.  Use this to review your
     strategies for getting production time.

     In the relativistic shock version (CODE = ``zirs''), there are in addi-
tion:

L BFLUX, R BFLUX  Cumulative magnetic field flux through the left and right
     sides.

XSHOCK

Notes
     The energies and momenta are the totals divided by Ly in versions peri-
odic in y, and by LxLy in versions periodic in x and y.


                                  The future


     User experience will guide evolution of ZED and of this report.
     It would not be difficult to teach ZED to read field information from
STATE and to read the particle files.



11/21/1988                             4
ZED

                               Customizing ZED

     The simplest customization is to add your own functions and macros in a
file to be read by Basis in addition to ZEDMAC.
     Other versions of ZOHAR, and other codes that write HISTORY files, have
STATE laid out differently, or no STATE file at all.  You can revise INIT and
GETSTATE accordingly; all the files are available in CFS.


                               Acknowledgements

     ZED derives its extensibility and its new power from the Basis system.
We are grateful for additions to Basis that ZED depends on.


                                  References


 [1] P. Dubois, Z. Motteler, P. Willmann et al, ``The Basis System'', LLNL
     report M-225, available on-line at the LCC and NMFECC.

 [2] ZOHAR is described in ``Electromagnetic and Relativistic Plasma Simula-
     tion Models'', A. B. Langdon and B. F. Lasinski, in Methods in Computa-
     tional Physics, ed. by B. Alder, S. Fernbach and M. Rotenberg, vol. ed.
     J. Killeen, (Academic Press, New York, 1976), Vol. 16, p. 327-366.


                           Appendix:  How it works



























11/21/1988                             5